home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / lib / perl5 / Gtk2 / CodeGen.pm next >
Encoding:
Perl POD Document  |  2005-07-26  |  10.1 KB  |  265 lines
  1. package Gtk2::CodeGen;
  2.  
  3. use strict;
  4. use warnings;
  5. use Carp;
  6. use IO::File;
  7. use base 'Glib::CodeGen';
  8.  
  9. our $VERSION = '0.03';
  10.  
  11.  
  12. Glib::CodeGen->add_type_handler (GtkObject => \&gen_gtkobject_stuff);
  13.  
  14.  
  15. =head1 NAME
  16.  
  17. Gtk2::CodeGen - code generation utilities for Glib-based bindings.
  18.  
  19. =head1 SYNOPSIS
  20.  
  21.  # usually in Makefile.PL
  22.  use Gtk2::CodeGen;
  23.  
  24.  # most common, use all defaults
  25.  Gtk2::CodeGen->parse_maps ('myprefix');
  26.  Gtk2::CodeGen->write_boot;
  27.  
  28.  # more exotic, change everything
  29.  Gtk2::CodeGen->parse_maps ('foo',
  30.                             input => 'foo.maps',
  31.                             header => 'foo-autogen.h',
  32.                             typemap => 'foo.typemap',
  33.                             register => 'register-foo.xsh');
  34.  Gtk2::CodeGen->write_boot (filename => 'bootfoo.xsh',
  35.                             glob => 'Foo*.xs',
  36.                             ignore => '^(Foo|Foo::Bar)$');
  37.  
  38. =head1 DESCRIPTION
  39.  
  40. This module packages some of the boilerplate code needed for performing code
  41. generation typically used by perl bindings for gobject-based libraries, using
  42. the Glib module as a base.
  43.  
  44. The default output filenames are in the subdirectory 'build', which usually
  45. will be present if you are using ExtUtils::Depends (as most Glib-based
  46. extensions probably should).
  47.  
  48. =head2 METHODS
  49.  
  50. =over
  51.  
  52. =item Gtk2::CodeGen->write_boot;
  53.  
  54. =item Gtk2::CodeGen->write_boot (KEY => VAL, ...)
  55.  
  56. Many GObject-based libraries to be bound to perl will be too large to put in
  57. a single XS file; however, a single PM file typically only bootstraps one
  58. XS file's code.  C<write_boot> generates an XSH file to be included from
  59. the BOOT section of that one bootstrapped module, calling the boot code for
  60. all the other XS files in the project.
  61.  
  62. Options are passed to the function in a set of key/val pairs, and all options
  63. may default.
  64.  
  65.   filename     the name of the output file to be created.
  66.                the default is 'build/boot.xsh'.
  67.  
  68.   glob         a glob pattern that specifies the names of
  69.                the xs files to scan for MODULE lines.
  70.                the default is 'xs/*.xs'.
  71.  
  72.   xs_files     use this to supply an explicit list of file
  73.                names (as an array reference) to use instead
  74.                of a glob pattern.  the default is to use
  75.                the glob pattern.
  76.  
  77.   ignore       regular expression matching any and all 
  78.                module names which should be ignored, i.e.
  79.                NOT included in the list of symbols to boot.
  80.                this parameter is extremely important for
  81.                avoiding infinite loops at startup; see the
  82.                discussion for an explanation and rationale.
  83.                the default is '^[^:]+$', or, any name that
  84.                contains no colons, i.e., any toplevel
  85.                package name.
  86.  
  87.  
  88. This function performs a glob (using perl's builtin glob operator) on the
  89. pattern specified by the 'glob' option to retrieve a list of file names.
  90. It then scans each file in that list for lines matching the pattern
  91. "^MODULE" -- that is, the MODULE directive in an XS file.  The module
  92. name is pulled out and matched against the regular expression specified
  93. by the ignore parameter.  If this module is not to be ignored, we next
  94. check to see if the name has been seen.  If not, the name will be converted
  95. to a boot symbol (basically, s/:/_/ and prepend "boot_") and this symbol
  96. will be added to a call to GPERL_CALL_BOOT in the generated file; it is then
  97. marked as seen so we don't call it again.
  98.  
  99.  
  100. What is this all about, you ask?  In order to bind an XSub to perl, the C
  101. function must be registered with the interpreter.  This is the function of the
  102. "boot" code, which is typically called in the bootstrapping process.  However,
  103. when multiple XS files are used with only one PM file, some other mechanism
  104. must call the boot code from each XS file before any of the function therein
  105. will be available.
  106.  
  107. A typical setup for a multiple-XS, single-PM module will be to call the 
  108. various bits of boot code from the BOOT: section of the toplevel module's
  109. XS file.
  110.  
  111. To use Gtk2 as an example, when you do 'use Gtk2', Gtk2.pm calls bootstrap
  112. on Gtk2, which calls the C function boot_Gtk2.  This function calls the
  113. boot symbols for all the other xs files in the module.  The distinction
  114. is that the toplevel module, Gtk2, has no colons in its name.
  115.  
  116.  
  117. C<xsubpp> generates the boot function's name by replacing the 
  118. colons in the MODULE name with underscores and prepending "boot_".
  119. We need to be careful not to include the boot code for the bootstrapped module,
  120. (say Toplevel, or Gtk2, or whatever) because the bootstrap code in 
  121. Toplevel.pm will call boot_Toplevel when loaded, and boot_Toplevel
  122. should actually include the file we are creating here.
  123.  
  124. The default value for the ignore parameter ignores any name not containing
  125. colons, because it is assumed that this will be a toplevel module, and any
  126. other packages/modules it boots will be I<below> this namespace, i.e., they
  127. will contain colons.  This assumption holds true for Gtk2 and Gnome2, but
  128. obviously fails for something like Gnome2::Canvas.  To boot that module
  129. properly, you must use a regular expression such as "^Gnome2::Canvas$".
  130.  
  131. Note that you can, of course, match more than just one name, e.g.
  132. "^(Foo|Foo::Bar)$", if you wanted to have Foo::Bar be included in the same
  133. dynamically loaded object but only be booted when absolutely necessary.
  134. (If you get that to work, more power to you.)
  135.  
  136. Also, since this code scans for ^MODULE, you must comment the MODULE section
  137. out with leading # marks if you want to hide it from C<write_boot>.
  138.  
  139. =cut
  140.  
  141. # sub write_boot is inherited from Glib::CodeGen.
  142.  
  143.  
  144. =item Gtk2::CodeGen->parse_maps (PREFIX, [KEY => VAL, ...])
  145.  
  146. Convention within Glib/Gtk2 and friends is to use preprocessor macros in the
  147. style of SvMyType and newSVMyType to get values in and out of perl, and to
  148. use those same macros from both hand-written code as well as the typemaps.
  149. However, if you have a lot of types in your library (such as the nearly 200
  150. types in Gtk+ 2.x), then writing those macros becomes incredibly tedious, 
  151. especially so when you factor in all of the variants and such.
  152.  
  153. So, this function can turn a flat file containing terse descriptions of the
  154. types into a header containing all the cast macros, a typemap file using them,
  155. and an XSH file containing the proper code to register each of those types
  156. (to be included by your module's BOOT code).
  157.  
  158. The I<PREFIX> is mandatory, and is used in some of the resulting filenames,
  159. You can also override the defaults by providing key=>val pairs:
  160.  
  161.   input    input file name.  default is 'maps'.  if this
  162.            key's value is an array reference, all the
  163.            filenames in the array will be scanned.
  164.   header   name of the header file to create, default is
  165.            build/$prefix-autogen.h
  166.   typemap  name of the typemap file to create, default is
  167.            build/$prefix.typemap
  168.   register name of the xsh file to contain all of the 
  169.            type registrations, default is build/register.xsh
  170.  
  171. the maps file is a table of type descriptions, one per line, with fields
  172. separated by whitespace.  the fields should be:
  173.  
  174.   TYPE macro    e.g., GTK_TYPE_WIDGET 
  175.   class name    e.g. GtkWidget, name of the C type
  176.   base type     one of GObject, GBoxed, GEnum, GFlags.
  177.                 GtkObject is also supported, but the
  178.                 distinction is no longer necessary as
  179.                 of Glib 0.26.
  180.   package       name of the perl package to which this
  181.                 class name should be mapped, e.g.
  182.                 Gtk2::Widget
  183.  
  184. As a special case, you can also use this same format to register error
  185. domains; in this case two of the four columns take on slightly different
  186. meanings:
  187.  
  188.   domain macro     e.g., GDK_PIXBUF_ERROR
  189.   enum type macro  e.g., GDK_TYPE_PIXBUF_ERROR
  190.   base type        GError
  191.   package          name of the Perl package to which this
  192.                    class name should be mapped, e.g.,
  193.                    Gtk2::Gdk::Pixbuf::Error.
  194.  
  195. =cut
  196.  
  197.  
  198. # sub parse_maps is inherited from Glib::CodeGen.
  199.  
  200.  
  201. #
  202. # GtkObject has different reference-counting semantics than GObject;
  203. # in particular, the _noinc variant is meaningless for GtkObjects,
  204. # as the bindings register gtk_object_sink().
  205. #
  206.  
  207. sub gen_gtkobject_stuff {
  208.     my ($typemacro, $classname, $root, $package) = @_;
  209.  
  210.     Glib::CodeGen::add_typemap "$classname *", "T_GPERL_GENERIC_WRAPPER";
  211.     Glib::CodeGen::add_typemap "const $classname *", "T_GPERL_GENERIC_WRAPPER";
  212.     Glib::CodeGen::add_typemap "$classname\_ornull *", "T_GPERL_GENERIC_WRAPPER";
  213.     Glib::CodeGen::add_typemap "const $classname\_ornull *", "T_GPERL_GENERIC_WRAPPER";
  214.     Glib::CodeGen::add_register "#ifdef $typemacro
  215. gperl_register_object ($typemacro, \"$package\");
  216. #endif /* $typemacro */";
  217.  
  218.     my $get_wrapper = 'gtk2perl_new_gtkobject (GTK_OBJECT (val))';
  219.     Glib::CodeGen::add_header "#ifdef $typemacro
  220.   /* $root derivative $classname */
  221. # define Sv$classname(sv)    (($classname*)gperl_get_object_check (sv, $typemacro))
  222. # define newSV$classname(val)    ($get_wrapper)
  223.   typedef $classname $classname\_ornull;
  224. # define Sv$classname\_ornull(sv)    (((sv) && SvOK (sv)) ? Sv$classname(sv) : NULL)
  225. # define newSV$classname\_ornull(val)    (((val) == NULL) ? &PL_sv_undef : $get_wrapper)
  226. #endif /* $typemacro */
  227. ";
  228. }
  229.  
  230.  
  231. 1;
  232. __END__
  233.  
  234. =back
  235.  
  236. =head1 SEE ALSO
  237.  
  238. L<Glib::CodeGen> does the actual work; Gtk2::CodeGen is now just a wrapper
  239. which adds support for gtk-specific types.
  240.  
  241. =head1 AUTHOR
  242.  
  243. muppet <scott at asofyet dot org>
  244.  
  245. =head1 COPYRIGHT
  246.  
  247. Copyright (C) 2003-2005 by the gtk2-perl team (see the file AUTHORS for the
  248. full list)
  249.  
  250. This library is free software; you can redistribute it and/or modify it under
  251. the terms of the GNU Library General Public License as published by the Free
  252. Software Foundation; either version 2.1 of the License, or (at your option)
  253. any later version.
  254.  
  255. This library is distributed in the hope that it will be useful, but WITHOUT
  256. ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  257. FOR A PARTICULAR PURPOSE.  See the GNU Library General Public License for
  258. more details.
  259.  
  260. You should have received a copy of the GNU Library General Public License
  261. along with this library; if not, write to the Free Software Foundation, Inc.,
  262. 59 Temple Place - Suite 330, Boston, MA  02111-1307  USA.
  263.  
  264. =cut
  265.